Skip to content

Drop AGENTS.md's migration list - #148

Merged
toruiwasa merged 2 commits into
mainfrom
docs/agents-md-migration-list
Sep 5, 2026
Merged

Drop AGENTS.md's migration list#148
toruiwasa merged 2 commits into
mainfrom
docs/agents-md-migration-list

Conversation

@toruiwasa

@toruiwasa toruiwasa commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Summary

AGENTS.md opened its Database section by enumerating the migrations, and the review on this pull request asked whether the list should come out rather than be finished. Reading the ten entries against the migrations they describe says yes, so this deletes the paragraph instead.

Each entry is a compression of the header of its own migration, including the first, whose note that the role and the hook are what everything later refers to reads as though it could only be said from outside the file. admin_role_and_access_token_hook.sql:4-5 already says This is the thing every later policy and grant refers to.

Nothing replaces it, and nothing moves

  • AGENTS.md:403 already opens Where the schema is decided, and in what order to read it, and what it lists is CONTEXT.md, the ADRs and the spec rather than supabase/migrations/. That reads as deliberate: the schema is decided in the spec and applied in the migrations, and the list was inventorying the application.
  • AGENTS.md:306 already says where the files are.
  • The third entry's note about the seed was the one candidate for moving. That same line describes seed/, AGENTS.md:462 records that the catalogue reaching production is a decision (Where the credential catalogue is permanently housed #95) rather than a side effect of a deploy, and the catalogues migration sends a reader of the empty table to the same issue.

What I kept

The clause on AGENTS.md:349 about a save's whole effect on the two child tables travelling through apply_profile_children() in one transaction. That is not a schema inventory, and the sentence it joins was stopping at the Server Action.

Related issue

None. Two of the three entries this started out adding were from pull requests of mine (#139 and #147), so it began as finishing my own work rather than proposing new work. Happy to open one if you would rather.

Two commits

969c2f3 is the original update, left as it is. c163563 is the deletion, so the diff between the two is the review.

Checklist

  • Opened as a draft pull request
  • pnpm lint passed, where applicable (Markdown only, nothing lints it)
  • pnpm test:e2e passed, where applicable (Markdown only)
  • Commit messages have no Co-Authored-By, Generated with, or tool-attribution trailers
  • Linked the closing issue (see above)

`AGENTS.md` opened its migration list with `There are seven migrations.` and then walked through seven. It was true when #120 wrote it and has been false since #121; there are ten on `main`. A reader following that paragraph as the map it is meant to be gets handed an inventory that is short by three, and nothing in the paragraph says so.

The count goes rather than moving to ten. A sentence naming a number plus a list of that many entries is a closed claim, and the next migration makes it a contradiction — falsified by anyone adding a file, without a line of `AGENTS.md` changing. A list with no count is a map: the next migration leaves a blank in it rather than a lie. The entries themselves were never wrong, and none of them is touched here.

What replaces it says whose job it is to keep the list whole, because nothing said so before and that is the likeliest reason two migrations fell out of it. The three that add neither a table nor a column are `20260822050002_profile_own_reads.sql`, `20260827124213_account_emails.sql` and `20260830092253_apply_profile_children.sql` — the first two are exactly the two that went missing, which is two out of two and so an observation rather than a cause, but it is the axis the sentence names.

The eighth entry is `my_profile()` and `my_credentials()` (#14), the ninth is `account_emails(uuid[])` (#123), the tenth is `apply_profile_children()` (#128). Each is written in the shape the seven above it use: what the migration establishes, and the one decision in it that a later change could undo without noticing. The eighth is somebody else's migration described in somebody else's document, so it is as close to the surrounding register as I could manage and should be rewritten freely.

The prose below the list gains one clause. It already named `my_profile()` and `my_credentials()` as how the editor reads, and stopped at "saves them with a Server Action" — which reads as though the writes go straight out of the Server Action, and that is the shape #128 replaced. It now says the child tables are written through `apply_profile_children()` in one transaction.

The paragraph is not restructured, and it grows from 462 words on one line to 924. Turning it into a list would make every future entry a one-line diff and would make this diff unreadable, so it is a separate question and not a contributor's to answer.

Nothing in the repository lints or tests Markdown, and `ci.yml` detects a documentation-only branch and skips the build, so there is no run to point at here.
@toruiwasa
toruiwasa marked this pull request as ready for review September 2, 2026 23:31
davidtaing
davidtaing previously approved these changes Sep 4, 2026

@davidtaing davidtaing left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @toruiwasa. I wonder if we should remove it from the AGENTS.md instead. Each time we create a migration means that we will have to update this each time.

The review on #148 asked whether the list should come out instead, and
reading the ten entries against the migrations they describe says yes.
Each one is a compression of the header of its own migration, including
the first, whose note that the role and the hook are what everything
later refers to reads as though it could only be said from outside the
file: `admin_role_and_access_token_hook.sql` says it in its own second
sentence.

Nothing replaces it. `:403` already opens `Where the schema is decided,
and in what order to read it`, and what it lists is `CONTEXT.md`, the
ADRs and the spec rather than `supabase/migrations/`, which reads as
deliberate: the schema is decided in the spec and applied in the
migrations, and the list was inventorying the application. `:306`
already says where the files are.

Nothing moves either. The third entry's note about the seed was the one
candidate, and `:306` describes `seed/`, `:462` records that the
catalogue reaching production is a decision (#95) rather than a side
effect of a deploy, and the catalogues migration sends a reader of the
empty table to the same issue.

The clause on `:349` from the commit below this one stays. A save's
whole effect on the two child tables travelling through
`apply_profile_children()` in one transaction is not a schema
inventory, and the sentence it joins was stopping at the Server Action.
@toruiwasa toruiwasa changed the title Bring AGENTS.md's migration list up to date Drop AGENTS.md's migration list Sep 5, 2026
@toruiwasa

Copy link
Copy Markdown
Collaborator Author

Thanks @davidtaing,
You are right, and I have replaced the update with the deletion.

Reading the ten entries against the migrations they describe:

  • Each one is already in the header of the migration it describes. Including the first, which reads as though it could only be said from outside the file: admin_role_and_access_token_hook.sql:4-5 already says This is the thing every later policy and grant refers to. The eighth is profile_own_reads.sql:12-31, and I wrote that one in this pull request.
  • Nothing is needed in its place. AGENTS.md:403 already opens Where the schema is decided, and in what order to read it, and what it lists is CONTEXT.md, the ADRs and the spec rather than supabase/migrations/.
  • Nothing needed moving either. The seed note in the third entry was the only candidate, and AGENTS.md:306, AGENTS.md:462 and catalogues.sql:33-36 already carry it between them.

It is a summary sitting in a file that is always loaded, which is worth something, and I did weigh that. It has drifted twice, at #121 and #139, and a stale summary that gets trusted instead of the source is worse than no summary.

969c2f3 is left as it is and the deletion sits on top. The clause on AGENTS.md:349 about a save travelling through apply_profile_children() stays.

@toruiwasa toruiwasa self-assigned this Sep 5, 2026
@toruiwasa
toruiwasa merged commit 9161aac into main Sep 5, 2026
1 check passed
@toruiwasa
toruiwasa deleted the docs/agents-md-migration-list branch September 5, 2026 03:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants